Move documentation to inline comments: GtkIconFactory

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index b2e1e758e9be3d874b912eea86acbbfb4b6cb459..6ad4cb70bda97661b60d4008a0e0a55c45ed83be 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -52,6 +52,7 @@ gtkhpaned.sgml
 gtkhscale.sgml
 gtkhscrollbar.sgml
 gtkhseparator.sgml
+gtkiconfactory.sgml
 gtkiconview.sgml
 gtkimagemenuitem.sgml
 gtkimcontext.sgml

diff --git a/docs/reference/gtk/tmpl/gtkiconfactory.sgml b/docs/reference/gtk/tmpl/gtkiconfactory.sgml
deleted file mode 100644 (file)
index b5e3a3e..0000000
--- a/docs/reference/gtk/tmpl/gtkiconfactory.sgml
+++ /dev/null
@@ -1,542 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Themeable Stock Images
-
-<!-- ##### SECTION Short_Description ##### -->
-
-Manipulating stock icons
-
-<!-- ##### SECTION Long_Description ##### -->
-
-
-<para>
-Browse the available stock icons in the list of stock IDs found <link
-linkend="gtk-Stock-Items">here</link>. You can also use 
-the <application>gtk-demo</application> application for this purpose.
-</para>
-
-<para>
- An icon factory manages a collection of #GtkIconSet; a #GtkIconSet manages a
- set of variants of a particular icon (i.e. a #GtkIconSet contains variants for
- different sizes and widget states). Icons in an icon factory are named by a
- stock ID, which is a simple string identifying the icon. Each #GtkStyle has a
- list of #GtkIconFactory derived from the current theme; those icon factories
- are consulted first when searching for an icon. If the theme doesn't set a
- particular icon, GTK+ looks for the icon in a list of default icon factories,
- maintained by gtk_icon_factory_add_default() and
- gtk_icon_factory_remove_default(). Applications with icons should add a default
- icon factory with their icons, which will allow themes to override the icons
- for the application.
-</para>
-
-<para>
-To display an icon, always use gtk_style_lookup_icon_set() on the widget that
-will display the icon, or the convenience function
-gtk_widget_render_icon(). These functions take the theme into account when
-looking up the icon to use for a given stock ID.
-</para>
-
-<refsect2 id="GtkIconFactory-BUILDER-UI"><title>GtkIconFactory as GtkBuildable</title>
-<para>
-GtkIconFactory supports a custom &lt;sources&gt; element, which 
-can contain multiple &lt;source&gt; elements. 
-The following attributes are allowed:
-<variablelist>
-
-<varlistentry>
-<term>stock-id</term>
-<listitem><para>The stock id of the source, a string.
-This attribute is mandatory</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>filename</term>
-<listitem><para>The filename of the source, a string.
-This attribute is optional</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>icon-name</term>
-<listitem><para>The icon name for the source, a string.
-This attribute is optional.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>size</term>
-<listitem><para>Size of the icon, a #GtkIconSize enum value. 
-This attribute is optional.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>direction</term>
-<listitem><para>Direction of the source, a #GtkTextDirection enum value.
-This attribute is optional.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>state</term>
-<listitem><para>State of the source, a #GtkStateType enum value.
-This attribute is optional.</para>
-</listitem>
-</varlistentry>
-
-</variablelist>
-
-</para>
-<example>
-<title>A <structname>GtkIconFactory</structname> UI definition fragment.</title>
-<programlisting><![CDATA[
-<object class="GtkIconFactory" id="iconfactory1">
-  <sources>
-    <source stock-id="apple-red" filename="apple-red.png"/>
-  </sources>
-</object>
-<object class="GtkWindow" id="window1">
-  <child>
-    <object class="GtkButton" id="apple_button">
-      <property name="label">apple-red</property>
-      <property name="use-stock">True</property>
-    </object>
-  </child>
-</object>
-]]></programlisting>
-</example>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkIconSource ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### STRUCT GtkIconFactory ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### STRUCT GtkIconSet ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ENUM GtkIconSize ##### -->
-<para>
-
-</para>
-
-@GTK_ICON_SIZE_INVALID: 
-@GTK_ICON_SIZE_MENU: 
-@GTK_ICON_SIZE_SMALL_TOOLBAR: 
-@GTK_ICON_SIZE_LARGE_TOOLBAR: 
-@GTK_ICON_SIZE_BUTTON: 
-@GTK_ICON_SIZE_DND: 
-@GTK_ICON_SIZE_DIALOG: 
-
-<!-- ##### FUNCTION gtk_icon_source_copy ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_free ##### -->
-<para>
-
-</para>
-
-@source: 
-
-
-<!-- ##### FUNCTION gtk_icon_factory_add ##### -->
-<para>
-
-</para>
-
-@factory: 
-@stock_id: 
-@icon_set: 
-
-
-<!-- ##### FUNCTION gtk_icon_factory_add_default ##### -->
-<para>
-
-</para>
-
-@factory: 
-
-
-<!-- ##### FUNCTION gtk_icon_factory_lookup ##### -->
-<para>
-
-</para>
-
-@factory: 
-@stock_id: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_factory_lookup_default ##### -->
-<para>
-
-</para>
-
-@stock_id: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_factory_new ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_factory_remove_default ##### -->
-<para>
-
-</para>
-
-@factory: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_add_source ##### -->
-<para>
-
-</para>
-
-@icon_set: 
-@source: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_copy ##### -->
-<para>
-
-</para>
-
-@icon_set: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_new ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_new_from_pixbuf ##### -->
-<para>
-
-</para>
-
-@pixbuf: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_ref ##### -->
-<para>
-
-</para>
-
-@icon_set: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_render_icon ##### -->
-<para>
-
-</para>
-
-@icon_set: 
-@style: 
-@direction: 
-@state: 
-@size: 
-@widget: 
-@detail: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_render_icon_pixbuf ##### -->
-<para>
-
-</para>
-
-@icon_set: 
-@context: 
-@size: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_unref ##### -->
-<para>
-
-</para>
-
-@icon_set: 
-
-
-<!-- ##### FUNCTION gtk_icon_size_lookup ##### -->
-<para>
-
-</para>
-
-@size: 
-@width: 
-@height: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_size_lookup_for_settings ##### -->
-<para>
-
-</para>
-
-@settings: 
-@size: 
-@width: 
-@height: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_size_register ##### -->
-<para>
-
-</para>
-
-@name: 
-@width: 
-@height: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_size_register_alias ##### -->
-<para>
-
-</para>
-
-@alias: 
-@target: 
-
-
-<!-- ##### FUNCTION gtk_icon_size_from_name ##### -->
-<para>
-
-</para>
-
-@name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_size_get_name ##### -->
-<para>
-
-</para>
-
-@size: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_set_get_sizes ##### -->
-<para>
-
-</para>
-
-@icon_set: 
-@sizes: 
-@n_sizes: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_direction ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_direction_wildcarded ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_filename ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_pixbuf ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_icon_name ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_size ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_size_wildcarded ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_state ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_get_state_wildcarded ##### -->
-<para>
-
-</para>
-
-@source: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_new ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_direction ##### -->
-<para>
-
-</para>
-
-@source: 
-@direction: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_direction_wildcarded ##### -->
-<para>
-
-</para>
-
-@source: 
-@setting: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_filename ##### -->
-<para>
-
-</para>
-
-@source: 
-@filename: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_pixbuf ##### -->
-<para>
-
-</para>
-
-@source: 
-@pixbuf: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_icon_name ##### -->
-<para>
-
-</para>
-
-@source: 
-@icon_name: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_size ##### -->
-<para>
-
-</para>
-
-@source: 
-@size: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_size_wildcarded ##### -->
-<para>
-
-</para>
-
-@source: 
-@setting: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_state ##### -->
-<para>
-
-</para>
-
-@source: 
-@state: 
-
-
-<!-- ##### FUNCTION gtk_icon_source_set_state_wildcarded ##### -->
-<para>
-
-</para>
-
-@source: 
-@setting: 
-
-

diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index 4e16bfbf378453a7483ec702af984c6f904a1be3..4feff1087fd89b14dfa49b5f670e95405c4cc2e4 100644 (file)
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -42,6 +42,107 @@
 #include "gtkbuilderprivate.h"
 #include "gtktypebuiltins.h"
 
+
+/**
+ * SECTION:gtkiconfactory
+ * @Short_description: Manipulating stock icons
+ * @Title: Themeable Stock Images
+ *
+ * Browse the available stock icons in the list of stock IDs found <link
+ * linkend="gtk-Stock-Items">here</link>. You can also use
+ * the <application>gtk-demo</application> application for this purpose.
+ *
+ * An icon factory manages a collection of #GtkIconSet; a #GtkIconSet manages a
+ * set of variants of a particular icon (i.e. a #GtkIconSet contains variants for
+ * different sizes and widget states). Icons in an icon factory are named by a
+ * stock ID, which is a simple string identifying the icon. Each #GtkStyle has a
+ * list of #GtkIconFactory derived from the current theme; those icon factories
+ * are consulted first when searching for an icon. If the theme doesn't set a
+ * particular icon, GTK+ looks for the icon in a list of default icon factories,
+ * maintained by gtk_icon_factory_add_default() and
+ * gtk_icon_factory_remove_default(). Applications with icons should add a default
+ * icon factory with their icons, which will allow themes to override the icons
+ * for the application.
+ *
+ * To display an icon, always use gtk_style_lookup_icon_set() on the widget that
+ * will display the icon, or the convenience function
+ * gtk_widget_render_icon(). These functions take the theme into account when
+ * looking up the icon to use for a given stock ID.
+ *
+ * <refsect2 id="GtkIconFactory-BUILDER-UI">
+ * <title>GtkIconFactory as GtkBuildable</title>
+ * <para>
+ * GtkIconFactory supports a custom &lt;sources&gt; element, which can contain
+ * multiple &lt;source&gt; elements.
+ * The following attributes are allowed:
+ * <variablelist>
+ * <varlistentry>
+ * <term>stock-id</term>
+ * <listitem><para>
+ * The stock id of the source, a string.
+ * This attribute is mandatory
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>filename</term>
+ * <listitem><para>
+ * The filename of the source, a string.
+ * This attribute is optional
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>icon-name</term>
+ * <listitem><para>
+ * The icon name for the source, a string.
+ * This attribute is optional.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>size</term>
+ * <listitem><para>
+ * Size of the icon, a #GtkIconSize enum value.
+ * This attribute is optional.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>direction</term>
+ * <listitem><para>
+ * Direction of the source, a #GtkTextDirection enum value.
+ * This attribute is optional.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>state</term>
+ * <listitem><para>
+ * State of the source, a #GtkStateType enum value.
+ * This attribute is optional.
+ * </para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ * <example>
+ * <title>A #GtkIconFactory UI definition fragment.</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkIconFactory" id="iconfactory1">
+ *   <sources>
+ *     <source stock-id="apple-red" filename="apple-red.png"/>
+ *   </sources>
+ * </object>
+ * <object class="GtkWindow" id="window1">
+ *   <child>
+ *     <object class="GtkButton" id="apple_button">
+ *       <property name="label">apple-red</property>
+ *       <property name="use-stock">True</property>
+ *     </object>
+ *   </child>
+ * </object>
+ * ]]>
+ * </programlisting>
+ * </example>
+ * </para>
+ * </refsect2>
+ */
+
+
 static GSList *all_icon_factories = NULL;
 
 struct _GtkIconFactoryPrivate